@cursor Check the code review findings and fix if applicable and valid, then create a PR to dev branch to remediate:

1. Codex review:
   pyproject.toml
   Comment on lines 18 to 22
   dependencies = [
   "json5>=0.9.28",
   "icontract>=2.7.1",
   "pytest>=8.4.2",
   "pytest-cov>=7.0.0",
   @chatgpt-codex-connector
   chatgpt-codex-connector bot
   10 hours ago
   P1 Badge Declare beartype in the default hatch environment

The new governance scripts import beartype unconditionally (scripts/sync_github_hierarchy_cache.py and scripts/validate_agent_rule_applies_when.py), but the default Hatch environment dependencies added here do not include beartype. In a fresh checkout (or any environment that has not separately installed specfact-cli), running python scripts/sync_github_hierarchy_cache.py (now required by AGENTS bootstrap) or hatch run validate-agent-rule-signals fails immediately with ModuleNotFoundError: beartype, so the new workflow cannot run as documented.

2. CoderabbitAI review (25 findings):

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @docs/agent-rules/50-quality-gates-and-review.md:

• Around line 39-49: The quality gate list omits the bundle-import validation
  step; update the "Quality gate order" sequence to include the command hatch run
  check-bundle-imports in the proper place (e.g., after yaml-lint or before
  verify-modules-signature) so the documented canonical order matches the updated
  pre-commit flow and local validation checklist; modify the ordered list under
  "Quality gate order" to insert hatch run check-bundle-imports and ensure
  surrounding steps (hatch run yaml-lint and hatch run verify-modules-signature)
  remain intact.

In @docs/agent-rules/60-github-change-governance.md:

• Around line 62-63: Replace the vague “about five minutes” with a precise
  freshness rule: treat .specfact/backlog/github_hierarchy_cache.md as stale if
  its recorded timestamp (use an explicit field like last_synced_at in the cache
  file or the file mtime) is older than 300 seconds (5 * 60) compared to the
  current UTC time; update the text and any checks that call python
  scripts/sync_github_hierarchy_cache.py to compare UTC now against last_synced_at
  (or mtime) using seconds to decide whether to run the sync.

In @docs/agent-rules/70-release-commit-and-docs.md:

• Line 45: Update Step 1 so branch-prefix guidance matches the bootstrap rules:
  allow branches rooted from origin/dev with prefixes feature/, bugfix/,
  hotfix/, or chore/ (and optionally note the expected worktree location under
  ../specfact-cli-modules-worktrees/) — or explicitly state if restricting to only
  feature/hotfix is intentional; modify the Step 1 text (the line "Branch from
  origin/dev into a feature or hotfix branch.") to enumerate the allowed
  prefixes or add the clarification.

In @openspec/CHANGE_ORDER.md:

• Line 78: The CHANGE_ORDER.md contains a pending entry for governance-03
  (identifier governance-03-github-hierarchy-cache) but this change is archived;
  remove the governance-03 row from the Pending table (or move it into an
  Archived/Removed section) and update any parent/paired references (e.g., the
  Parent Feature link to #163 and paired specfact-cli#491 mention) so the pending
  table reflects only active change artifacts and avoids drift.

In
@openspec/changes/archive/2026-04-09-governance-03-github-hierarchy-cache/specs/backlog-sync/spec.md:

• Around line 1-4: Add a top-level heading and ensure blank lines surround each
  heading in the spec to satisfy markdown validation: insert a top-level H1 (e.g.,
  "Archived Specs" or similar) above the existing "## MODIFIED Requirements", and
  add a single blank line before and after each heading such as "## MODIFIED
  Requirements" and "### Requirement: Restore backlog sync command functionality"
  (and other headings referenced on lines 3, 12, 17, 21, 25, 31) so the spec.md
  file, which mentions specfact backlog sync, has proper spacing and a top-level
  heading.

In
@openspec/changes/governance-04-deterministic-agent-governance-loading/CHANGE_VALIDATION.md:

• Around line 27-34: Update the validation summary so it does not claim PASS
  when the mandatory full review is failing: change the header/result from
  "Result: PASS" to indicate PENDING/BLOCKED and add a clear note that
  .specfact/code-review.json produced 934 findings and the full-review gate must
  pass before marking the change validated; keep the existing details about
  .specfact/code-review.changed.json passing and the commands used (hatch run specfact code review run --json --out .specfact/code-review.json and the
  changed-scope command) so readers see both outcomes and the required action to
  re-run the full command until the full review passes.

In
@openspec/changes/governance-04-deterministic-agent-governance-loading/proposal.md:

• Around line 1-3: Add a top-level Markdown title before the existing "## Why"
  heading to satisfy markdownlint and improve document structure; insert a line
  like "# Proposal: Deterministic Agent Governance Loading" at the top of the
  proposal (keeping the existing "## Why" section intact) so the document begins
  with a single H1 heading.

In
@openspec/changes/governance-04-deterministic-agent-governance-loading/specs/agent-governance-loading/spec.md:

• Around line 1-14: The spec is missing a top-level heading; open
  specs/agent-governance-loading/spec.md and add a top-level H1 heading
  "Specification: Agent Governance Loading" above the existing "## ADDED
  Requirements" line so the document conforms to markdownlint and matches the
  pattern used in proposal.md; ensure the exact heading text is used and placed as
  the first non-blank line of the file.

In
@openspec/changes/governance-04-deterministic-agent-governance-loading/TDD_EVIDENCE.md:

• Around line 44-47: Summary: The full-repo SpecFact quality gate still fails
  (934 findings) causing release promotion to be blocked; either fix findings or
  add an approved exception. Fix: run the exact verification command shown (hatch run specfact code review run --json --out .specfact/code-review.json --scope full) to regenerate .specfact/code-review.json, triage and remediate the
  reported findings (start with high-severity items such as the legacy
  packages/specfact-backlog/src/specfact_backlog/backlog/commands.py complexity
  issues), or if remediation is infeasible create an explicit, approved exception
  record in the release checklist for this PR referencing task 4.2 and attach
  the .specfact/code-review.json artifact and justification; update the PR
  description/checklist to point to the exception and ensure an approver signs off
  before merge.

In
@openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-add/spec.md:

• Around line 3-6: The markdown headings are missing required blank lines
  (MD022) which breaks markdownlint; update the spec by inserting a single blank
  line after the "Requirement: Backlog add local artifact helpers SHALL preserve
  user-managed content" heading and another blank line after the "Scenario:
  Existing local config is not silently replaced" heading so each heading is
  followed by an empty line, ensuring the document adheres to markdownlint rules.

In
@openspec/changes/project-runtime-01-safe-artifact-write-policy/specs/backlog-sync/spec.md:

• Around line 1-6: Add a top-level H1 and ensure blank lines surround the
  existing headings to satisfy markdownlint (MD041/MD022): insert a single H1 at
  the top of the file (for example "Backlog sync requirements" or similar), then
  ensure there is a blank line before and after "## ADDED Requirements", and add
  blank lines before and after "### Requirement: Backlog sync local export paths
  SHALL avoid silent overwrites" and before and after "#### Scenario: Existing
  export target produces conflict or safe merge" so each heading has the required
  surrounding blank lines.

In @openspec/changes/project-runtime-01-safe-artifact-write-policy/tasks.md:

• Around line 23-25: Reorder the checklist so quality gates run in the canonical
  sequence: ensure the hatch run format, hatch run type-check, and hatch run lint remain first, then list hatch run yaml-lint followed immediately by
  verify-modules-signature (add or rename the step to verify-modules-signature
  if needed), then run hatch run contract-test, then the relevant
  smart-test/test coverage, and finally the .specfact/code-review.json
  review step; move the version bump / re-sign changed manifests remediation (the
  current 4.4) to immediately after verify-modules-signature so package
  version/signature fixes occur before contract-test, and keep recording the
  final review timestamp in TDD_EVIDENCE.md or PR notes as the last action.

In @openspec/specs/github-hierarchy-cache/spec.md:

• Around line 3-5: The Purpose section of this spec file (heading "Purpose") is
  still "TBD" and must be replaced with a self-contained description of what the
  github-hierarchy-cache spec standardizes; update the "Purpose" heading to a
  concise summary that explains scope, intended behavior, and how it relates to
  archived-change governance-03-github-hierarchy-cache, and ensure the
  "Requirements" section references any CHANGE_ORDER, drift/shipping constraints
  and the openspec/**/*.md conventions so the spec is complete before merging.

In @README.md:

• Line 56: Update the README run-sequence so the standalone final code-review
  gate is explicitly listed and matches the pre-commit path: add the command
  "hatch run specfact code review run --json --out .specfact/code-review.json" (or
  the equivalent "specfact code review run --json --out
  .specfact/code-review.json" if already run in a hatch context) into the top “Run
  this sequence” block after tests, ensuring the sequence reads: format →
  type-check → lint → yaml-lint → verify-modules-signature → contract-test →
  smart-test → test → specfact code review; mention the same helper behavior
  referenced by pre-commit-quality-checks.sh block2 and
  scripts/pre_commit_code_review.py so manual local validation matches the
  required governance order.

In @scripts/pre-commit-quality-checks.sh:

• Around line 149-169: The run_code_review_gate function only collects staged
  Python files via staged_python_files and so skips review for non-Python contract
  changes; change it to gather all review-relevant staged paths (not just
  .py/.pyi) by calling the staged files helper that returns all staged paths
  (e.g., staged_files or staged_paths) and filter/include files under packages/,
  registry/, scripts/, tools/, tests/, and openspec/changes/* (but exclude any
  TDD_EVIDENCE.md) before invoking scripts/pre_commit_code_review.py; ensure the
  collected list is passed to scripts/pre_commit_code_review.py the same way
  ${py_array[@]} currently is and update the info/warn messages to reflect the
  broader file set in run_code_review_gate.
• Around line 209-218: The current short-circuit in run_block2() uses
  check_safe_change() too broadly and lets edits to tooling/config (e.g.,
  pyproject.toml or this pre-commit script) skip the review and contract-test
  decision; narrow the safe-change logic so tooling/config files do not trigger
  the fast path by updating check_safe_change() usage or its predicate inside
  run_block2() to exclude repo metadata that defines the quality pipeline (ensure
  changes to pyproject.toml, scripts/pre-commit-quality-checks.sh, and other
  pipeline-defining files bypass the safe path), then keep print_block2_overview,
  run_code_review_gate and run_contract_tests_visible executing for those changes.

In @scripts/sync_github_hierarchy_cache.py:

• Around line 336-348: The fingerprint currently includes updated_at (causing
  unnecessary churn) and omits fields that affect rendered output; in
  compute_hierarchy_fingerprint replace updated_at with the exact fields used when
  rendering the cache (e.g., include issue.url and issue.summary and any other
  rendered inputs you write out such as title, labels, parent_number,
  child_numbers) and keep deterministic ordering (sorted labels, sorted children
  by number) so the hash reflects only rendered-output-relevant data; adjust the
  canonical_rows construction in compute_hierarchy_fingerprint/HierarchyIssue
  accordingly.
• Around line 98-100: The GraphQL subIssues connection currently uses
  subIssues(first: 100) without pageInfo and the code does not handle nested
  pagination, causing silent truncation; update the query to request pageInfo {
  hasNextPage endCursor } for subIssues and modify the GraphQL-fetching logic that
  builds the issue hierarchy (the code handling the subIssues connection /
  response) to iterate using endCursor while hasNextPage to fetch all pages,
  merging nodes across pages, or alternatively detect hasNextPage and raise a
  clear error to prevent silent truncation; ensure the final hierarchy/fingerprint
  includes all children and that any error path logs the problematic parent issue
  number/URL.

In @scripts/validate_agent_rule_applies_when.py:

• Around line 55-59: path.read_text can raise OSError/UnicodeDecodeError and
  currently crashes the validator; wrap the call to
  path.read_text(encoding="utf-8") in a try/except that catches OSError and
  UnicodeDecodeError, append a structured validation entry to the existing errors
  list (e.g. f"{path.name}: failed to read file: {err}") and continue the loop,
  then only call _parse_frontmatter(text) if read succeeded so parsed handling
  remains unchanged.
• Around line 66-68: In validate_agent_rule_applies_when
  (scripts/validate_agent_rule_applies_when.py) stop coercing list items to text:
  when raw is a list, validate each entry is either a str or None and if any item
  has a different type raise a TypeError with a clear message identifying
  "applies_when" entries; only after validation build signals as the list of
  strings (i.e., keep items as-is, not str(item)) and filter out None. This
  replaces the current signals = [str(item) for item in raw if item is not None]
  with explicit type checks and an immediate error on malformed types.

In @src/specfact_cli_modules/dev_bootstrap.py:

• Around line 58-62: The code uses os.environ.setdefault(...) which preserves
  any previously exported SPECFACT_MODULES_REPO / SPECFACT_REPO_ROOT; instead,
  always overwrite with the current checkout values: replace
  os.environ.setdefault("SPECFACT_MODULES_REPO", str(resolved)) with an assignment
  that sets os.environ["SPECFACT_MODULES_REPO"] = str(resolved), and if core is
  not None replace os.environ.setdefault("SPECFACT_REPO_ROOT", str(core)) with
  os.environ["SPECFACT_REPO_ROOT"] = str(core); locate these changes around the
  resolved = repo_root.resolve() and core = resolve_core_repo(repo_root) usage in
  dev_bootstrap.py.

In @tests/unit/docs/test_agent_rules_governance.py:

• Around line 68-74: The test function
  test_agents_references_canonical_rule_docs verifies AGENTS.md contains specific
  doc references and section text but the file lacks a trailing newline; open
  AGENTS.md and add a single POSIX-compliant newline at EOF (ensure the file ends
  with "\n") so the test environment and tools that expect a trailing newline
  won't complain when running test_agents_references_canonical_rule_docs.

In @tests/unit/scripts/test_pre_commit_code_review.py:

• Around line 89-98: Extract the repeated mocked report payload into a single
  shared test fixture/object and reuse it instead of inlining it twice;
  specifically create a variable (e.g., sample_review_report =
  {"overall_verdict":"FAIL","findings":[{"severity":"error","rule":"e1"},{"severity":"warning","rule":"w1"}]})
  near the top of the test module and replace the inline literal passed to
  _write_sample_review_report(repo_root, ...) with that variable in all
  occurrences so the test_pre_commit_code_review.py assertions stay consistent and
  easier to maintain.

In @tests/unit/scripts/test_sync_github_hierarchy_cache.py:

• Around line 459-474: Wrap the test body in a try/finally (or use a teardown
  fixture) so cleanup always runs: after setting subprocess.run to _no_git via
  monkeypatch.setattr and importing the module via _load_script_module(), ensure
  _load_script_module.cache_clear() and
  sys.modules.pop("sync_github_hierarchy_cache", None) are invoked in a finally
  block; this guarantees that the monkeypatched subprocess.run is restored and the
  import cache is cleared even if the assertion in
  test_default_repo_name_falls_back_when_git_unavailable fails.

In @tests/unit/tools/test_contract_first_smart_test.py:

• Around line 44-61: Add a third "happy-path" unit test in
  tests/unit/tools/test_contract_first_smart_test.py that patches
  cfst_mod._git_staged_names to return a contract-relevant path (e.g.,
  "contracts/some_contract.yaml" or any path your code treats as contract-related)
  and assert cfst_mod._contract_test_status() == 1; reference the existing tests
  for structure and reuse monkeypatch and the cfst_mod fixture, and ensure the new
  test name makes intent clear (e.g.,
  test_contract_test_status_returns_one_for_relevant_staged).

Outside diff comments:
In @openspec/specs/backlog-sync/spec.md:

• Around line 7-33: Update the spec text to explicitly pin the repo-local
  hierarchy cache path and state file names so adapters and specfact-cli share a
  canonical contract: replace ambiguous instances of "repo-local hierarchy cache"
  with the explicit paths .specfact/backlog/github_hierarchy_cache.md for the
  human-readable hierarchy and the accompanying state JSON (e.g.,
  .specfact/backlog/github_hierarchy_cache.state.json), and add a short sentence
  in the "Cache-first hierarchy lookup for parent issue assignment" scenario
  noting that tools MUST read/write those exact files and only fall back to GitHub
  when those files are missing or stale; reference the command specfact backlog sync and the alias specfact backlog ceremony sync so the change is visible to
  consumers.

Here is what I did and where it landed.

PR

PR #184 — branch cursor/coderabbit-remediation-011e → dev

Codex (beartype)

• Added beartype>=0.22.0 to the default Hatch env in pyproject.toml so python scripts/sync_github_hierarchy_cache.py and hatch run validate-agent-rule-signals work without a separate specfact-cli install.

CodeRabbit / tooling (high impact)

• scripts/sync_github_hierarchy_cache.py: Paginates subIssues via a dedicated GraphQL query (no silent >100-child truncation). compute_hierarchy_fingerprint now hashes fields that match rendered output (url, summary, labels, parent/children) and drops updated_at from the fingerprint payload.
• scripts/pre-commit-quality-checks.sh: check_safe_change no longer treats pyproject.toml / scripts/pre-commit-quality-checks.sh / scripts/pre_commit_code_review.py / tools/contract_first_smart_test.py as “safe” for skipping Block 2. run_code_review_gate passes staged paths under packages/, registry/, scripts/, tools/, tests/, openspec/changes/ (skips TDD_EVIDENCE.md).
• scripts/pre_commit_code_review.py: filter_review_gate_paths mirrors that policy (replaces Python-only filtering).
• src/specfact_cli_modules/dev_bootstrap.py: apply_specfact_workspace_env always sets SPECFACT_MODULES_REPO / SPECFACT_REPO_ROOT (no stale setdefault). Test updated accordingly.
• scripts/validate_agent_rule_applies_when.py: Safe file reads; applies_when list entries must be str or null (non-strings are reported as validation errors).
• tools/contract_first_smart_test.py: Staged paths under contracts/ trigger contract-test (with tests).

Docs / OpenSpec

• Quality gate order includes check-bundle-imports; README sequence adds check-bundle-imports and explicit hatch run specfact code review run --json --out .specfact/code-review.json.
• openspec/specs/backlog-sync/spec.md: Pins .specfact/backlog/github_hierarchy_cache.md and .specfact/backlog/github_hierarchy_cache_state.json; references specfact backlog sync / ceremony alias.
• openspec/specs/github-hierarchy-cache/spec.md: Replaces TBD purpose with a real scope statement.
• openspec/CHANGE_ORDER.md: Moves archived governance-03 to Implemented; trims pending row; keeps #491 reference on governance-04 baseline text.
• Markdown structure fixes in archived governance-03 backlog-sync spec, governance-04 proposal/spec/validation, project-runtime OpenSpec specs/tasks; CHANGE_VALIDATION / TDD_EVIDENCE clarify full-review PENDING/BLOCKED.

Tests / gates run locally

• hatch run format, type-check, lint, yaml-lint, check-bundle-imports, hatch run test → 545 passed (project test helper runs full tree).
• verify-modules-signature --require-signature failed in this environment (missing public key for bundle verification), noted in the PR body.